﻿<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
	<title xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory">Chapter 20. EPL Reference: Spatial Methods and Indexes</title>
	<link rel="stylesheet" href="css/espertech.css" type="text/css">
	<meta xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" name="generator" content="DocBook XSL-NS Stylesheets V1.74.0">
	<meta xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<link rel="home" href="index.html" title="Esper Reference">
	<link rel="up" href="index.html" title="Esper Reference">
	<link rel="prev" href="script.html" title="Chapter 19. Script Support">
	<link rel="next" href="dataflow.html" title="Chapter 21. EPL Reference: Data Flow">
</head>

<body>
	<p xmlns:d="http://docbook.org/ns/docbook" id="title"><a href="./index.html" class="site_href"><strong>www.espertech.com</strong></a><a href="http://www.espertech.com/esper/esper-documentation/" class="doc_href"><strong>Documentation</strong></a></p>
	<ul xmlns:d="http://docbook.org/ns/docbook" class="docnav">
		<li class="previous"><a accesskey="p" href="script.html"><strong>Prev</strong></a></li>
		<li class="next"><a accesskey="n" href="dataflow.html"><strong>Next</strong></a></li>
	</ul>
	<div class="chapter" lang="en-US">
		<div class="titlepage">
			<div>
				<div>
					<h2 class="title"><a id="spatial"></a>Chapter 20. EPL Reference: Spatial Methods and Indexes</h2>
				</div>
			</div>
		</div>
		<div class="toc">
			<dl>
				<dt><span class="sect1"><a href="spatial.html#spatial_intro">20.1. Overview</a></span></dt>
				<dt><span class="sect1"><a href="spatial.html#spatial_method">20.2. Spatial Methods</a></span></dt>
				<dd>
					<dl>
						<dt><span class="sect2"><a href="spatial.html#spatial_method_pointinsiderectangle">20.2.1. Point-Inside-Rectangle</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_method_rectangleintersectsrectangle">20.2.2. Rectangle-Intersects-Rectangle</a></span></dt>
					</dl>
				</dd>
				<dt><span class="sect1"><a href="spatial.html#spatial_index">20.3. Spatial Index - Quadtree</a></span></dt>
				<dd>
					<dl>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_overview">20.3.1. Overview</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_pointregionquadtreedeclare">20.3.2. Declaring a Point-Region Quadtree Index</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_pointregionquadtreefilterindex">20.3.3. Using a Point-Region Quadtree as a Filter Index</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_pointregionquadtreeeventindex">20.3.4. Using a Point-Region Quadtree as an Event Index</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_mxcifquadtreedeclare">20.3.5. Declaring a MX-CIF Quadtree Index</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_mxcifquadtreefilterindex">20.3.6. Using a MX-CIF Quadtree as a Filter Index</a></span></dt>
						<dt><span class="sect2"><a href="spatial.html#spatial_index_mxcifquadtreeeventindex">20.3.7. Using a MX-CIF Quadtree as an Event Index</a></span></dt>
					</dl>
				</dd>
				<dt><span class="sect1"><a href="spatial.html#spatial_etc">20.4. Spatial Types, Functions and Methods from External Libraries</a></span></dt>
			</dl>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="spatial_intro"></a>20.1. Overview</h2>
					</div>
				</div>
			</div><a id="d0e50250" class="indexterm"></a>
			<p>
				EPL provides spatial methods and spatial indexes.
			</p>
			<p>
				The compiler analyzes filter criteria and the <code class="literal">where</code>-clause and considers spatial methods, utilizing spatial filter indexes or spatial event indexes for efficient matching and lookup.
			</p>
			<p>
				For general information on the dot-operator please consult <a class="xref" href="epl-operator.html#epl-operator-ref-dot" title="9.7. Dot Operator">Section 9.7, “Dot Operator”</a>.
			</p>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="spatial_method"></a>20.2. Spatial Methods</h2>
					</div>
				</div>
			</div><a id="d0e50269" class="indexterm"></a><a id="d0e50274" class="indexterm"></a>
			<p>
				The below table summarizes the built-in spatial methods available:
			</p>
			<div class="table"><a id="spatial_method_table"></a>
				<p class="title"><b>Table 20.1. Spatial Methods</b></p>
				<div class="table-contents">
					<table summary="Spatial Methods" border="1">
						<colgroup>
							<col>
							<col>
						</colgroup>
						<thead>
							<tr>
								<th>Method</th>
								<th>Result</th>
							</tr>
						</thead>
						<tbody>
							<tr>
								<td>point(x,y).inside(rectangle(x,y,width,height))</td>
								<td>
									<p>
										Returns true if the point is inside the rectangle.
									</p>
									<p>
										<a class="xref" href="spatial.html#spatial_method_pointinsiderectangle" title="20.2.1. Point-Inside-Rectangle">Section 20.2.1, “Point-Inside-Rectangle”</a>.
									</p>
								</td>
							</tr>
							<tr>
								<td>rectangle(x,y,width,height).intersects(rectangle(x,y,width,height))</td>
								<td>
									<p>
										Returns true if the rectangle intersects with the rectangle.
									</p>
									<p>
										<a class="xref" href="spatial.html#spatial_method_rectangleintersectsrectangle" title="20.2.2. Rectangle-Intersects-Rectangle">Section 20.2.2, “Rectangle-Intersects-Rectangle”</a>.
									</p>
								</td>
							</tr>
						</tbody>
					</table>
				</div>
			</div><br class="table-break">
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_method_pointinsiderectangle"></a>20.2.1. Point-Inside-Rectangle</h3>
						</div>
					</div>
				</div>
				<p>
					The method compares a point to a rectangle and returns true if the point falls inside the rectangle.
				</p>
				<p>
					The method takes a point as input and a rectangle as a parameter:
				</p>
				<pre class="synopsis">point(<span class="emphasis"><em>point_x</em></span>, <span class="emphasis"><em>point_y</em></span> [, filterindex:<span class="emphasis"><em>configexpression</em></span>]).inside(rectangle(<span class="emphasis"><em>rect_x</em></span>, <span class="emphasis"><em>rect_y</em></span>, <span class="emphasis"><em>width</em></span>, <span class="emphasis"><em>height</em></span>))</pre>
				<p>
					For the point, please provide the <span class="emphasis"><em>point_x</em></span> and <span class="emphasis"><em>point_y</em></span> expressions that return the (x, y)-coordinates of the point.
					The <code class="literal">filterindex</code> named parameter is for use with filter indexes as described below.
					The left-hand side point can be subject to point-region quadtree indexing (MX-CIF quadtrees do not apply).
				</p>
				<p>
					For the rectangle, the <span class="emphasis"><em>rect_x</em></span> expression and <span class="emphasis"><em>rect_y</em></span> expressions return the (x, y)-coordinates of the rectangle and the <span class="emphasis"><em>width</em></span> expression and <span class="emphasis"><em>height</em></span> expressions return the width and height of the rectangle.
				</p>
				<p>
					All expressions must return a number-type and the implementation compares the <code class="literal">double</code>-values returned by the expressions.
				</p>
				<p>
					A point is considered inside the rectangle if <code class="literal">(point_x &gt;= rect_x) and (point_x &lt; rect_x + width) and (point_y &gt;= rect_y) and (point_y &lt; rect_y + height)</code>.
				</p>
				<div class="table"><a id="spatial_method_pointinsiderectangle_example"></a>
					<p class="title"><b>Table 20.2. Point-Inside-Rectangle Examples</b></p>
					<div class="table-contents">
						<table summary="Point-Inside-Rectangle Examples" border="1">
							<colgroup>
								<col>
								<col>
							</colgroup>
							<thead>
								<tr>
									<th>Expression</th>
									<th>Result</th>
								</tr>
							</thead>
							<tbody>
								<tr>
									<td>
										<pre class="synopsis">point(10, 20).inside(rectangle(0, 0, 50, 50))</pre>
									</td>
									<td>true</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">point(10, 20).inside(rectangle(20, 20, 50, 50))</pre>
									</td>
									<td>false</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">point(10, 20).inside(rectangle(9, 19, 1, 1))</pre>
									</td>
									<td>false</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">point(10, 20).inside(rectangle(9, 19, 1.0001, 1.0001))</pre>
									</td>
									<td>true</td>
								</tr>
							</tbody>
						</table>
					</div>
				</div><br class="table-break">
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_method_rectangleintersectsrectangle"></a>20.2.2. Rectangle-Intersects-Rectangle</h3>
						</div>
					</div>
				</div>
				<p>
					The method compares a rectangle to a rectangle and returns true if the rectangles intersect.
				</p>
				<p>
					The method takes a rectangle as input and a rectangle as a parameter:
				</p>
				<pre class="synopsis">rectangle(<span class="emphasis"><em>rect_x</em></span>, <span class="emphasis"><em>rect_y</em></span>, <span class="emphasis"><em>rect_width</em></span>, <span class="emphasis"><em>rect_height</em></span> [, filterindex:<span class="emphasis"><em>configexpression</em></span>]).intersects(rectangle(<span class="emphasis"><em>other_x</em></span>, <span class="emphasis"><em>other_y</em></span>, <span class="emphasis"><em>other_width</em></span>, <span class="emphasis"><em>other_height</em></span>))</pre>
				<p>
					The left-hand side is the rectangle's <span class="emphasis"><em>rect_x</em></span>, <span class="emphasis"><em>rects_y</em></span>, <span class="emphasis"><em>rect_width</em></span> and <span class="emphasis"><em>rect_height</em></span> expressions
					that return the (x, y)-coordinates and the size of the rectangle.
					The <code class="literal">filterindex</code> named parameter is for use with filter indexes as described below.
					The left-hand side rectangle can be subject to MX-CIF quadtree indexing (point-region quadtrees do not apply).
				</p>
				<p>
					For the compared-to rectangle on the right-hand side, the <span class="emphasis"><em>other_x</em></span>, <span class="emphasis"><em>other_y</em></span>, <span class="emphasis"><em>other_width</em></span> and <span class="emphasis"><em>other_height</em></span> expressions return the (x, y)-coordinates and size of the compared-to rectangle.
				</p>
				<p>
					All expressions must return a number-type and the implementation compares the <code class="literal">double</code>-values returned by the expressions.
				</p>
				<p>
					A rectangle is considered to intersect another rectangle if:
				</p>
				<div class="itemizedlist">
					<ul>
						<li>
							<p><code class="literal">rect_x + rect_width &gt;= other_x</code> (a is not left of b) and</p>
						</li>
						<li>
							<p><code class="literal">rect_x &lt;= other_x + other_width</code> (a is not right of b) and</p>
						</li>
						<li>
							<p><code class="literal">rect_y + rect_height &gt;= other_y</code> (a is not above b) and</p>
						</li>
						<li>
							<p><code class="literal">rect_y &lt;= other_y + other_height</code> (a is not below b).</p>
						</li>
					</ul>
				</div>
				<div class="table"><a id="spatial_method_rectangleintersectsrectangle_example"></a>
					<p class="title"><b>Table 20.3. Rectangle-Intersects-Rectangle Examples</b></p>
					<div class="table-contents">
						<table summary="Rectangle-Intersects-Rectangle Examples" border="1">
							<colgroup>
								<col>
								<col>
							</colgroup>
							<thead>
								<tr>
									<th>Expression</th>
									<th>Result</th>
								</tr>
							</thead>
							<tbody>
								<tr>
									<td>
										<pre class="synopsis">rectangle(10, 20, 5, 5).intersects(rectangle(0, 0, 50, 50))</pre>
									</td>
									<td>true</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">rectangle(10, 20, 5, 5).intersects(rectangle(20, 20, 50, 50))</pre>
									</td>
									<td>false</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">rectangle(10, 20, 5, 5).intersects(rectangle(9, 19, 1, 1))</pre>
									</td>
									<td>true</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">rectangle(10, 20, 5, 5).intersects(rectangle(9, 19, 0.999, 0.999))</pre>
									</td>
									<td>false</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">rectangle(10, 20, 5, 5).intersects(rectangle(15, 25, 1, 1))</pre>
									</td>
									<td>true</td>
								</tr>
								<tr>
									<td>
										<pre class="synopsis">rectangle(10, 20, 5, 5).intersects(rectangle(15.001, 25.001, 1, 1))</pre>
									</td>
									<td>false</td>
								</tr>
							</tbody>
						</table>
					</div>
				</div><br class="table-break">
			</div>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="spatial_index"></a>20.3. Spatial Index - Quadtree</h2>
					</div>
				</div>
			</div><a id="d0e50569" class="indexterm"></a><a id="d0e50574" class="indexterm"></a>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_overview"></a>20.3.1. Overview</h3>
						</div>
					</div>
				</div>
				<p>
					A quadtree is a tree data structure in which each branch node has exactly four children.
					Quadtrees are often used to partition a two-dimensional space by recursively subdividing it into four quadrants or regions (source:WikiPedia).
				</p>
				<p>
					Quadtree indexes can be used for:
				</p>
				<div class="itemizedlist">
					<ul>
						<li>
							<p>Filter indexes, which organize active filters so that they can be searched efficiently. When the runtime receives an event, it consults the filter indexes to determine which statements, if any, must process the event.</p>
						</li>
						<li>
							<p>Event indexes, which organize properties of events so that they can be searched efficiently. When the runtime performs statement processing it may use event indexes to find correlated events efficiently.</p>
						</li>
					</ul>
				</div>
				<p>
					The <span class="emphasis"><em>point-region quadtree</em></span> is a quadtree for the efficient finding of points that fall inside a given rectangle. Use this index with the point-inside-rectangle method described above.
				</p>
				<p>
					The <span class="emphasis"><em>MX-CIF quadtree</em></span> is a quadtree for the efficient finding of rectangles that intersect with a given rectangle. Use this index with the rectangle-intersects-rectangle method described above.
				</p>
				<p>
					While point-region quadtree and MX-CIF quadtree are similar, they are not compatible and are not the same. In point-region quadtree, only leaf nodes have data. In MX-CIF quadtrees both branch and leaf nodes have data as branches hold rectangles that don't fit any given quadrant. The runtime expands and shrinks both types of trees dynamically based on data by promoting or subdividing a leaf node to branch nodes when adding data and by demoting or merging branches to a leaf node when removing data.
				</p>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_pointregionquadtreedeclare"></a>20.3.2. Declaring a Point-Region Quadtree Index</h3>
						</div>
					</div>
				</div>
				<p>
					Declaring a point-region quadtree index is the same for both filter indexes and event indexes.
					Point-region quadtrees are suitable for efficiently finding points inside a rectangle, when there are many points.
				</p>
				<p>
					The synopsis to declare a point-region quadtree index, as part of a statement, is:
				</p>
				<pre class="synopsis">pointregionquadtree(<span class="emphasis"><em>min_x_expression</em></span>, <span class="emphasis"><em>min_y_expression</em></span>, 
  <span class="emphasis"><em>width</em></span>, <span class="emphasis"><em>height</em></span> [, <span class="emphasis"><em>leaf_capacity_expression</em></span> [, <span class="emphasis"><em>max_tree_height_expression</em></span>]])</pre>
				<p>
					The <span class="emphasis"><em>min_x_expression</em></span>, <span class="emphasis"><em>min_y_expression</em></span>, <span class="emphasis"><em>width</em></span>, <span class="emphasis"><em>height</em></span> are index parameter expressions
					that return the range of the index. The width and height must be greater zero. The index range rectangle is represented by <code class="literal">double</code>-type values internally.
					A point is inside the index range if <code class="literal">x &gt;= minX and y &gt;= minY and x &lt; minX+width and y &lt; minY+height</code>.
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="note">
					<h2>Note</h2>
					<p>
						An attempt to insert points into the index that are outside of the declared index range causes an exception.
					</p>
				</div>
				<p>
					The <span class="emphasis"><em>leaf_capacity_expression</em></span> is optional and must return a positive integer. It defines the number of coordinates a node may contain before it gets split into regions.
					The default value is 4.
				</p>
				<p>
					The <span class="emphasis"><em>max_tree_height_expression</em></span> is optional and must return an integer value of 2 or more. It defines the maximum depth of the tree.
					Upon the tree reaching the maximum depth a leaf node does not get split into regions. The default value is 20.
				</p>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_pointregionquadtreefilterindex"></a>20.3.3. Using a Point-Region Quadtree as a Filter Index</h3>
						</div>
					</div>
				</div>
				<p>
					The section that summarizes filter indexes is <a class="xref" href="processingmodel.html#processingmodel_indexes_filterindexes" title="2.18.2. Filter Indexes">Section 2.18.2, “Filter Indexes”</a>.
					As there could be many <code class="literal">point(...).inside(rectangle)</code> filters active, having a filter index allows the runtime to efficiently match incoming events to statements.
				</p>
				<p>
					For use of a point-region quadtree index within filter criteria you must:
				</p>
				<div class="itemizedlist">
					<ul>
						<li>
							<p>Define an expression that returns the point-region quadtree configuration, making sure it specifies <code class="literal">pointregionquadtree</code>.</p>
						</li>
						<li>
							<p>Add the <code class="literal">filterindex</code> named parameter providing the expression name.</p>
						</li>
					</ul>
				</div>
				<p>
					For defining a local or global expression, please consult <a class="xref" href="epl_clauses.html#epl-syntax-expression-decl" title="5.2.9. Expression Declaration">Section 5.2.9, “Expression Declaration”</a>.
				</p>
				<p>
					This sample statement defines the point-region quadtree filter index to have a bounding box of <code class="literal">(0,0,100,100)</code>:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">expression myPointRegionQuadtreeSettings { pointregionquadtree(0, 0, 100, 100) } 
select * from RectangleEvent(point(0, 0, filterindex:myPointRegionQuadtreeSettings).inside(rectangle(x, y, width, height)))</pre>
				<p>
					The <code class="literal">filterindex</code> named parameter instructs the runtime that the settings for the point-region quadtree filter index are provided by the expression <code class="literal">myPointRegionQuadtreeSettings</code>, a local expression in this example.
					For sharing point-region quadtree settings across statements you may use a global expression instead. Please see <a class="xref" href="epl_clauses.html#create-exprglobal" title="5.18. Declaring Global Expressions, Aliases and Scripts: Create Expression">Section 5.18, “Declaring Global Expressions, Aliases and Scripts: Create Expression”</a>.
				</p>
				<p>
					If your EPL does not specify <code class="literal">filterindex</code> the runtime does not build a point-region quadtree filter index.
				</p>
				<p>
					If your EPL specifies <code class="literal">filterindex</code> the runtime always builds and uses a point-region quadtree filter index.
					In the case the compiler analyses filter criteria and determines that it cannot use the point-region quadtree filter index, the compiler fails statement validation.
				</p>
				<p>
					If your EPL specifies <code class="literal">filterindex</code> and the compiler determines that it cannot use the point-region quadtree filter index it fails statement validation.
				</p>
				<p>
					The runtime shares point-region quadtree filter indexes across the runtime within the same event type given that:
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist">
					<ol>
						<li>
							<p>Filters have the same <code class="literal">rectangle</code> expressions.</p>
						</li>
						<li>
							<p>Filters use the same <code class="literal">filterindex</code> parameter i.e. the text <code class="literal">myPointRegionQuadtreeSettings</code> in above example.</p>
						</li>
						<li>
							<p>Filters use the same point-region quadtree index configuration i.e. <code class="literal">pointregionquadtree(0,0,100,100)</code> in above example.</p>
						</li>
					</ol>
				</div>
				<p>
					For use with the <code class="literal">filterindex</code> named parameter, the following requirements apply towards <code class="literal">point</code> expressions:
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist">
					<ol>
						<li>
							<p>Point expressions must be a constant, a context-provided built-in property or an event property provided by a previous pattern match within the same pattern.</p>
						</li>
					</ol>
				</div>
				<p>
					For use with the <code class="literal">filterindex</code> named parameter, the following requirements apply towards <code class="literal">rectangle</code> expressions:
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist">
					<ol>
						<li>
							<p>Rectangle expressions must be event properties.</p>
						</li>
					</ol>
				</div>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_pointregionquadtreeeventindex"></a>20.3.4. Using a Point-Region Quadtree as an Event Index</h3>
						</div>
					</div>
				</div>
				<p>
					The section that summarizes event indexes is <a class="xref" href="processingmodel.html#processingmodel_indexes_eventindexes" title="2.18.3. Event Indexes">Section 2.18.3, “Event Indexes”</a>. The <code class="literal">create index</code> clause is described in <a class="xref" href="nwtable.html#named_explicit_index" title="6.9. Explicitly Indexing Named Windows and Tables">Section 6.9, “Explicitly Indexing Named Windows and Tables”</a>.
				</p>
				<p>
					Declare a point-region quadtree event index as follows:
				</p>
				<pre class="synopsis">create index ... on ... (
  (<span class="emphasis"><em>x_expression</em></span>, <span class="emphasis"><em>y_expression</em></span>) pointregionquadtree(<span class="emphasis"><em>pointregion_quadtree_configuration</em></span>)
)</pre>
				<p>
					The <span class="emphasis"><em>x_expression</em></span> and <span class="emphasis"><em>y_expression</em></span> expressions form the index columns.
					The expressions return the (x, y)-coordinates and must return numeric values. Coordinates are represented as <code class="literal">double</code>-type values internally.
					See above for the <span class="emphasis"><em>pointregion_quadtree_configuration</em></span> point-region quadtree configuration.
				</p>
				<p>
					For example, assume a table that contains points:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create table PointTable(pointId string primary key, px double, py double)</pre>
				<p>
					This example EPL declares an index on the points, with <code class="literal">px</code> and <code class="literal">py</code> becoming index columns that determine (x, y)-coordinates:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create index PointIndex on PointTable((px, py) pointregionquadtree(0, 0, 100, 100))</pre>
				<p>
					The above sample quadtree index expects (x, y)-coordinates that are in the range <code class="literal">0 &lt;= px &lt;= 100</code> and <code class="literal">0 &lt;= py &lt;= 100</code>.
				</p>
				<p>
					The example schema for events providing rectangles is:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create schema RectangleEvent(rx double, ry double, w double, h double)</pre>
				<p>
					This EPL outputs, upon arrival of a RectangleEvent, all points that fall inside the rectangle:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">on RectangleEvent
select pointId from PointTable
where point(px, py).inside(rectangle(rx, ry, w, h))</pre>
				<p>
					Internally the runtime does not instantiate point or rectangle objects at all but instead optimizes the expression to comparison between <code class="literal">double</code>-type values.
				</p>
				<div class="sect3" lang="en-US">
					<div class="titlepage">
						<div>
							<div>
								<h4 class="title"><a id="spatial_index_pointregionquadtreeusenotes"></a>20.3.4.1. Point-Region Quadtree Event Index Usage Notes</h4>
							</div>
						</div>
					</div>
					<p>
						Point-Region quadtree indexes allow computed values for both index columns and index parameters. For example, the following EPL declares an index wherein (x, y)-coordinates are <code class="literal">(px/100, py/100)</code>-values. The sample EPL assumes that <code class="literal">context.frame</code> is a built-in property as provided by context <code class="literal">FramedCtx</code>:
					</p>
					<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">context FramedCtx create index PointIndex on PointTable((Math.round(px/100), Math.round(py/100)) pointregionquadtree(context.frame.startx, context.frame.starty, context.frame.w, context.frame.h))</pre>
					<p>
						The compiler compares the index column expressions to the <code class="literal">point-inside-rectangle</code> left-hand-side expressions to determine which index to use.
						For example, if the expression is <code class="literal">point(px+1, py+1).inside(rectangle(rx, ry, w, h))</code>
						as <code class="literal">(px+1, py+1)</code> does not match <code class="literal">(Math.round(px/100), Math.round(py/100))</code> the query planner does not use the index.
						If the expression is <code class="literal">point(Math.round(px/100), Math.round(py/100)).inside(rectangle(rx, ry, w, h))</code> the query planner does use the index as index column expressions match.
					</p>
					<p>
						The query planner prefers point-region quadtree over other index types. Index hints are not yet available for query planning with quadtree indexes.
					</p>
				</div>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_mxcifquadtreedeclare"></a>20.3.5. Declaring a MX-CIF Quadtree Index</h3>
						</div>
					</div>
				</div>
				<p>
					Declaring a MX-CIF quadtree index is the same for both filter indexes and event indexes.
					MX-CIF quadtrees are suitable for efficiently finding rectangles that intersect with a rectangle, when there are many rectangles.
				</p>
				<p>
					The synopsis to declare a MX-CIF quadtree index, as part of a statement, is:
				</p>
				<pre class="synopsis">mxcifquadtree(<span class="emphasis"><em>min_x_expression</em></span>, <span class="emphasis"><em>min_y_expression</em></span>, 
  <span class="emphasis"><em>width</em></span>, <span class="emphasis"><em>height</em></span> [, <span class="emphasis"><em>leaf_capacity_expression</em></span> [, <span class="emphasis"><em>max_tree_height_expression</em></span>]])</pre>
				<p>
					The <span class="emphasis"><em>min_x_expression</em></span>, <span class="emphasis"><em>min_y_expression</em></span>, <span class="emphasis"><em>width</em></span>, <span class="emphasis"><em>height</em></span> are index parameter expressions
					that return the range of the index. The width and height must be greater zero. The index range rectangle is represented by <code class="literal">double</code>-type values internally.
					A given rectangle must intersect with the index range.
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="note">
					<h2>Note</h2>
					<p>
						An attempt to insert rectangles into the index that do not intersect with the declared index range causes an exception.
					</p>
				</div>
				<p>
					The <span class="emphasis"><em>leaf_capacity_expression</em></span> is optional and must return a positive integer. It defines the number of coordinates a node may contain before it gets split into regions.
					The default value is 4.
				</p>
				<p>
					The <span class="emphasis"><em>max_tree_height_expression</em></span> is optional and must return an integer value of 2 or more. It defines the maximum depth of the tree.
					Upon the tree reaching the maximum depth a leaf node does not get split into regions. The default value is 20.
				</p>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_mxcifquadtreefilterindex"></a>20.3.6. Using a MX-CIF Quadtree as a Filter Index</h3>
						</div>
					</div>
				</div>
				<p>
					The section that summarizes filter indexes is <a class="xref" href="processingmodel.html#processingmodel_indexes_filterindexes" title="2.18.2. Filter Indexes">Section 2.18.2, “Filter Indexes”</a>.
					As there could be many <code class="literal">rectangle(...).intersects(rectangle)</code> filters active, having a filter index allows the runtime to efficiently match incoming events to statements.
				</p>
				<p>
					For use of a MX-CIF quadtree index within filter criteria you must:
				</p>
				<div class="itemizedlist">
					<ul>
						<li>
							<p>Define an expression that returns the MX-CIF quadtree configuration, making sure it specifies <code class="literal">mxcifquadtree</code>.</p>
						</li>
						<li>
							<p>Add the <code class="literal">filterindex</code> named parameter providing the expression name.</p>
						</li>
					</ul>
				</div>
				<p>
					For defining a local or global expression, please consult <a class="xref" href="epl_clauses.html#epl-syntax-expression-decl" title="5.2.9. Expression Declaration">Section 5.2.9, “Expression Declaration”</a>.
				</p>
				<p>
					This sample statement defines the MX-CIF quadtree filter index to have a bounding box of <code class="literal">(0,0,100,100)</code>:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">expression myMXCIFQuadtreeSettings { mxcifquadtree(0, 0, 100, 100) } 
select * from RectangleEvent(rectangle(10, 20, 5, 5, filterindex:myMXCIFQuadtreeSettings).intersects(rectangle(x, y, width, height)))</pre>
				<p>
					The <code class="literal">filterindex</code> named parameter instructs the compiler that the settings for the MX-CIF quadtree filter index are provided by the expression <code class="literal">myMXCIFQuadtreeSettings</code>, a local expression in this example.
					For sharing MX-CIF quadtree settings across statements you may use a global expression instead. Please see <a class="xref" href="epl_clauses.html#create-exprglobal" title="5.18. Declaring Global Expressions, Aliases and Scripts: Create Expression">Section 5.18, “Declaring Global Expressions, Aliases and Scripts: Create Expression”</a>.
				</p>
				<p>
					If your EPL does not specify <code class="literal">filterindex</code> the runtime does not build a MX-CIF quadtree filter index.
				</p>
				<p>
					If your EPL specifies <code class="literal">filterindex</code> the runtime always builds and uses a MX-CIF quadtree filter index.
					In the case the compiler analyses filter criteria and determines that it cannot use the MX-CIF quadtree filter index, the compiler fails statement validation.
				</p>
				<p>
					If your EPL specifies <code class="literal">filterindex</code> and the compiler determines that it cannot use the MX-CIF quadtree filter index it fails statement validation.
				</p>
				<p>
					The runtime shares MX-CIF quadtree filter indexes across the runtime within the same event type given that:
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist">
					<ol>
						<li>
							<p>Filters have the same <code class="literal">rectangle</code> expressions.</p>
						</li>
						<li>
							<p>Filters use the same <code class="literal">filterindex</code> parameter i.e. the text <code class="literal">myMXCIFQuadtreeSettings</code> in above example.</p>
						</li>
						<li>
							<p>Filters use the same MX-CIF quadtree index configuration i.e. <code class="literal">mxcifquadtree(0,0,100,100)</code> in above example.</p>
						</li>
					</ol>
				</div>
				<p>
					For use with the <code class="literal">filterindex</code> named parameter, the following requirements apply towards left-hand side <code class="literal">rectangle</code> expressions:
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist">
					<ol>
						<li>
							<p>Left-hand side rectangle expressions must be a constant, a context-provided built-in property or an event property provided by a previous pattern match within the same pattern.</p>
						</li>
					</ol>
				</div>
				<p>
					For use with the <code class="literal">filterindex</code> named parameter, the following requirements apply towards right-hand side <code class="literal">rectangle</code> expressions:
				</p>
				<div xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist">
					<ol>
						<li>
							<p>Right-hand side rectangle expressions must be event properties.</p>
						</li>
					</ol>
				</div>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="spatial_index_mxcifquadtreeeventindex"></a>20.3.7. Using a MX-CIF Quadtree as an Event Index</h3>
						</div>
					</div>
				</div>
				<p>
					The section that summarizes event indexes is <a class="xref" href="processingmodel.html#processingmodel_indexes_eventindexes" title="2.18.3. Event Indexes">Section 2.18.3, “Event Indexes”</a>. The <code class="literal">create index</code> clause is described in <a class="xref" href="nwtable.html#named_explicit_index" title="6.9. Explicitly Indexing Named Windows and Tables">Section 6.9, “Explicitly Indexing Named Windows and Tables”</a>.
				</p>
				<p>
					Declare a MX-CIF quadtree event index as follows:
				</p>
				<pre class="synopsis">create index ... on ... (
  (<span class="emphasis"><em>x_expression</em></span>, <span class="emphasis"><em>y_expression</em></span>, <span class="emphasis"><em>width_expression</em></span>, <span class="emphasis"><em>height_expression</em></span>) mxcifquadtree(<span class="emphasis"><em>mxcif_quadtree_configuration</em></span>)
)</pre>
				<p>
					The <span class="emphasis"><em>x_expression</em></span>, <span class="emphasis"><em>y_expression</em></span>, <span class="emphasis"><em>width_expression</em></span> and <span class="emphasis"><em>height_expression</em></span> expressions form the index columns.
					The expressions return the (x, y)-coordinates and rectangle size and must return numeric values. Coordinates and sizes are represented as <code class="literal">double</code>-type values internally.
					See above for the <span class="emphasis"><em>mxcif_quadtree_configuration</em></span> MX-CIF quadtree configuration.
				</p>
				<p>
					For example, assume a table that contains rectangles:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create table RectangleTable(rectangleId string primary key, rx double, ry double, rwidth double, rheight double)</pre>
				<p>
					This example EPL declares an index on the rectangles, with <code class="literal">rx</code>, <code class="literal">ry</code>, <code class="literal">rwidth</code> and <code class="literal">rheight</code> becoming index columns that determine the (x, y)-coordinates and the sizes:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create index RectangleIndex on RectangleTable((rx, ry, rwidth, rheight) mxcifquadtree(0, 0, 100, 100))</pre>
				<p>
					The above sample quadtree index expects rectangles to intersect the rectangle <code class="literal">(0, 0, 100, 100)</code>.
				</p>
				<p>
					The example schema for arriving events is:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create schema OtherRectangleEvent(otherX double, otherY double, otherWidth double, otherHeight double)</pre>
				<p>
					This EPL outputs, upon arrival of a <code class="literal">OtherRectangleEvent</code>, all rectangles stored in the table that intersect the arriving-events rectangle:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">on OtherRectangleEvent
select rectangleId from RectangleTable
where rectangle(rx, ry, rwidth, rheight).intersects(rectangle(otherX, otherY, otherWidth, otherHeight))</pre>
				<p>
					Internally the runtime does not instantiate rectangle objects at all but instead optimizes the expression to comparison between <code class="literal">double</code>-type values.
				</p>
				<div class="sect3" lang="en-US">
					<div class="titlepage">
						<div>
							<div>
								<h4 class="title"><a id="spatial_index_mxcifquadtreeusenotes"></a>20.3.7.1. MX-CIF Quadtree Event Index Usage Notes</h4>
							</div>
						</div>
					</div>
					<p>
						MX-CIF quadtree indexes allow computed values for both index columns and index parameters. For example, the following EPL declares an index wherein (x, y)-coordinates are <code class="literal">(px/100, py/100)</code>-values. The sample EPL assumes that <code class="literal">context.frame</code> is a built-in property as provided by context <code class="literal">FramedCtx</code>:
					</p>
					<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">context FramedCtx create index RectangleIndex on RectangleTable((Math.round(rx/100), Math.round(ry/100), Math.round(rwidth/100), Math.round(rheight/100)) mxcifquadtree(context.frame.startx, context.frame.starty, context.frame.w, context.frame.h))</pre>
					<p>
						The compiler compares the index column expressions to the <code class="literal">rectangle-interwsects-rectangle</code> left-hand-side expressions to determine which index to use.
					</p>
					<p>
						The query planner prefers MX-CIF quadtree over other index types. Index hints are not yet available for query planning with quadtree indexes.
					</p>
				</div>
			</div>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="spatial_etc"></a>20.4. Spatial Types, Functions and Methods from External Libraries</h2>
					</div>
				</div>
			</div><a id="d0e51167" class="indexterm"></a><a id="d0e51172" class="indexterm"></a><a id="d0e51177" class="indexterm"></a>
			<p>
				The scope of the compiler and runtime does not include addressing all geographical, topological or spatial processing.
				We encourage using external libraries for library calls.
				EPL makes it easy to use and extend EPL, using functions, methods, data types and data structures provided by external libraries.
			</p>
			<p>
				For example, assume you would like to use a geometric data type and the geographical distance function.
				Please consider using the Java Topology Suite (JTS) (<code class="literal">https://www.locationtech.org</code>) which provides a pretty complete set of geo computing functionality.
			</p>
			<p>
				To pick an example data type, the compiler and runtime allow any class such as the JTS Geometry class (<code class="literal">org.locationtech.jts.geom.Geometry</code>) to become an event type, an event property type or a column type in a named window, table.
				The compiler and runtime also allow the use of such class anywhere within EPL expressions.
			</p>
			<p>
				The EPL snippet below declares an event type that has a Geometry property:
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create schema ShapeArrivalEvent(shapeId string, geometry org.locationtech.jts.geom.Geometry) // use imports to remove the need to have a package name</pre>
			<p>
				EPL can call methods and your application can declare its own functions. Registering an own EPL function is described in <a class="xref" href="extension.html#custom-singlerow-function" title="22.2. Single-Row Function">Section 22.2, “Single-Row Function”</a>.
			</p>
			<p>
				This sample EPL outputs events that have a <code class="literal">distance</code> of more than 100 comparing the current event's <code class="literal">geometry</code> to the last 1 minute of previous event's <code class="literal">geometry</code>:
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">select * from ShapeArrivalEvent as e1 unidirectional, ShapeArrivalEvent.time(1 minute) as e2
where e1.geometry.distance(e2.geometry) &gt; 100</pre>
		</div>
	</div>
	<ul xmlns:d="http://docbook.org/ns/docbook" class="docnav">
		<li class="previous"><a accesskey="p" href="script.html"><strong>Prev</strong>Chapter 19. Script Support</a></li>
		<li class="up"><a accesskey="u" href="#"><strong>Top of page</strong></a></li>
		<li class="home"><a accesskey="h" href="index.html"><strong>Front page</strong></a></li>
		<li class="next"><a accesskey="n" href="dataflow.html"><strong>Next</strong>Chapter 21. EPL Reference: Data Flow</a></li>
	</ul>
</body>

</html>